Game Maker SQLite DLL By IsmAvatar
Document best viewed with word-wrap on.

Function quick-reference:

* ty_real sopen(ty_string fn)
* ty_real sclose(ty_real db)
* ty_real serrcode(ty_real db)
* ty_string serrmsg(ty_real db)
* ty_real squery(ty_real db, ty_string sql)
* ty_real sfree(ty_real qry)
* ty_real sstep(ty_real qry)
* ty_real sreset(ty_real qry)
* ty_real sdouble(ty_real qry, ty_real col)
* ty_string stext(ty_real qry, ty_real col)
* ty_real schanges(ty_real db)
* ty_real slastid(ty_real db)


Some function may return an error code. This is the negative of the actual error code from SQLite. See  http://www.sqlite.org/c3ref/c_abort.html for a listing of error codes. Notice that 0 indicates a success. Also notice that 100 and 101 are special cases that this dll handles seperately, so it should never return -100 or -101. Also notice that these error codes will always be negative, so you can quickly check a function to see if an error occurred by testing if it returns less than 0 (or less than 1 for some functions). Some function do not return an error code.

Notice, this dll is meant to be a quick and direct wrapper for SQLite. Not all of the SQLite functions are mapped; only the most common ones. It allocates memory for 5 databases and only 5 queries. It is also designed to make calls as fast as it can, which means that it does not perform extensive error checking, as that is too time-consuming, so if you do something stupid, like forget to open a database or query, or accidentally close it, and then try to use another function on that database or query, your program will likely crash because the dll encounters a NULL. SQLite's internal error checking is still performed, though, so passing in an invalid query will gracefully return an error code informing you of such.

* ty_real sopen(ty_string fn)
Opens a connection to a database file. Please limit 5 open databases at a time. This will return a database id that must be passed in to most other function calls. Do not close a database if it this returns an error, as that was already taken care of for you. Notice that if this returns an error code, you cannot use serrmsg to find out what went wrong. Instead, just look up the error code manually.
@return > 0 : The database id
@return = 0 : Too many open databases (limit 5, consider closing a db)
@return < 0 : An error code
@fn : The filename for the database. Path is optional.

* ty_real sclose(ty_real db)
Closes an open database connection. Do not close a database if you are not done with it, otherwise function calls that depend on that database will fail. Attempting to close a database that has open queries will return an error code. Notice that if you close the database on a pending transaction, the transaction will be rolled back. Do not close a database if it did not successfully open, as that has already been taken care of for you.
@return = 0 : Success
@return < 0 : An error code
@db : The database id

* ty_real serrcode(ty_real db)
Returns the error code returned from the last function call. You should not call this function if the last function call did not return an error. Notice that unlike other functions which return the negative error code, this function returns the positive error code.
@return > 0 : The last error code, positive. See http://www.sqlite.org/c3ref/c_abort.html
@db : The database id

* ty_string serrmsg(ty_real db)
Returns the last error message. If no errors occurred, this will return a string stating that.
@return : The last error message
@db : The database id

* ty_real squery(ty_real db, ty_string sql)
Prepares a given query. Returns a query id which must be passed to other functions that work on the query. After preparing a query, you must call sstep on the query in order for it to be executed. Notice you can only have 5 queries total "open" at any given time, independant of how many databases you have open. That is, it doesn't matter if you have 5 databases open, you still only get 5 queries to share amongst those 5 databases. So remember to free your queries after you're done with them, otherwise you will run out of queries quickly. Do not free a query if this returns an error, as that was already taken care of for you.
@return > 0 : The query id
@return = 0 : Too many open queries (limit 5, consider freeing a query)
@return < 0 : An error code
@db : The database id
@sql : The query you wish to execute, in Structured Query Language (SQL) accepted by SQLite.

* ty_real sstep(ty_real qry)
Executes given "open" query, or fetches the next row of data in the case of a SELECT. This must be called on all queries in order for them to be executed, and for SELECTs this must be called before fetching the first row of data. The retrieved row does not need to be closed or freed, as this is taken care of when you fetch the next row or free the query. Do not call this on a query that squery failed on or that has been closed.
@return = 1 : Successfully fetched a row of data.
@return = 0 : Successfully completed execution. No more rows were fetched, and you should not call sstep on this query again unless you call reset.
@return < 0 : An error code
@qry : The query id

* ty_real sfree(ty_real qry)
Frees, or "closes", an "open" query. It is very important to free your queries as soon as you are done with them or else you will run out of queries very quickly. Do *not* free a query if squery returns an error, as that was already taken care of for you. *Do* free a query even if sstep fails. This always returns 0.
@return = 0 : Success
@qry : The query id

* ty_real sreset(ty_real qry)
Resets the given query, so that calling sstep will fetch the first row again. This is useful for if you reach the last row of a query and want to go through it again.
@return = 0 : Success
@return < 0 : An error code

* ty_real sdouble(ty_real qry, ty_real col)
Returns the numerical value of the given column. sstep must have been called on the given query and must have returned 1 before calling this function.
@return : The numerical or "double" value of the given column. If the column data is not in double format, it will be converted.
@qry : The query id
@col : The column. The first column is 0.

* ty_string stext(ty_real qry, ty_real col)
Returns the string value of the given column. sstep must have been called on the given query and must have returned 1 before calling this function.
@return : The string or "text" value of the given column
@qry : The query id
@col : The column. The first column is 0.

* ty_real schanges(ty_real db)
Returns the number of rows modified by the last query performed on this database. Only changes by an INSERT, UPDATE, or DELETE statement are counted. To get the number of rows returned by a SELECT statement, you must either perform a seperate query with count(), or else go through each row, counting them one at a time, until you run out of rows. Notice, "DELETE FROM table" causes this function to return 0. To get an accurate count, use "DELETE FROM table WHERE 1" instead. This is a speed optimization implemented by SQLite.
@return >= 0 : The number of changed rows from the last query
@db : The database id

* ty_real slastid(ty_real db)
Returns the rowid (or primary key) of the most recent successful INSERT in this database. A successful INSERT is still considered successful even if it is subsequently rolled back.
@return > 0 : The rowid of the last successful insert query
@return = 0 : No insert queries have been successful
@db : The database id